PMake is a program designed to make the maintenance of other programs much easier. Its input is a ``makefile'' that specifies which files depend on which other files and what to do about files that are ``out-of-date.'' If you don't specify a makefile to read, Makefile and makefile, in that order, are looked for and read if they exist.
This manual page is meant to be a reference page only. For a more thorough description of PMake please refer to PMake -- A Tutorial(available in this distribution).
There are four basic types of lines in a makefile:
Any line may be continued over multiple lines by ending it with a backslash. The backslash, following newline and any initial whitespace on the following line are compressed into a single space.
On a dependency line, there are targets, sources and an operator. The targets ``depend'' on the sources and are usually created from them. Any number of targets and sources may be specified on a dependency line. All the targets in the line are made to depend on all the sources. If you run out of room, use a backslash at the end of the line to continue onto the next one.
Any file may be a target and any file may be a source, but the relationship between them is determined by the ``operator'' that separates them. Three operators are defined:
For example:
a : a.o b.o c.o
b ! d.o e.o
c :: f.o
command1
a : g.o
b ! h.o
c ::
command2
specifies that a depends on a.o, b.o, c.o and g.o and will be remade only if out-of-date with respect to these four files. b depends on d.o, e.o and h.o and will always be remade, but only after these three files have been remade. c will be remade with command1 if it is out-of-date with respect to f.o, as for the colon operator, while command2 will always be executed.
Targets and sources may also contain standard shell wildcard characters (?, *, [ and {}), but the ?, *, [ and ] characters may only be used in the final component of the target or source. If a target or source contains only curly braces and no other wildcard characters, it need not describe an existing file. Otherwise, only existing files will be used. E.g. the pattern
{a,b,c}.o
will expand to
a.o b.o c.o
regardless of whether these three files exist, while
[abc].o
will only expand to this if all three files exist. The resulting expansion is in directory order, not alphabetically sorted as in the shell.
Each target has associated with it a sort of shell script made up of a series of shell commands. The creation script for a target should immediately follow the dependency line for that target. Each of the commands in this script must be preceded by a tab character.
While any given target may appear on more than one dependency line, only one of these dependency lines may be followed by a creation script, unless the "::" operator is used.
One helpful feature of PMake is the ability to squirrel away commands for a target to be executed when everything else has been done. To do this, make one of the commands for the target be just ``...'' (an ellipsis) on a line by itself. The ellipsis itself won't be executed, of course, but any commands in the target's script that follow the ellipsis will be saved until PMake is done processing everything it needs to process. If you were to say,
a.o : a.c
cc -c a.c
...
@echo "All done"
Then the command ``echo "All done"'' would execute once everything else had finished. Note that this will only happen if ``a.o'' is found to be out-of-date.
There is another way in which makefile shell commands differ from regular shell commands, as illustrated in the above makefile scrap. The first two characters after the initial tab (and any other whitespace) are treated specially. If they are any combination of `@' and `-', (``@'', ``@-'', ``-@'' or ``-''), they cause PMake to do different things.
In most cases, shell commands are printed to the screen before they're actually executed. This is to keep you informed of what's going on. If an `@' appears, however, this echoing is suppressed. In the case of the echo command, above, this makes sense. It would look silly to see
echo "All done" All done
so PMake allows you to avoid that (this sort of echo control is only available if you use the Bourne or C shells to execute your commands, since the commands are echoed by the shell, not by PMake
The other special character is the `-'. Shell commands exit with a certain ``exit status.'' Normally this status will be 0 if everything went ok and non-zero if something went wrong. For this reason, PMake will consider an error to have occurred if one of the commands it invokes returns a non-zero status. When it detects an error, its usual action is to stop working, wait for everything in process to finish, and exit with a non-zero status itself. This behavior can be altered, however, by means of -i or -k arguments, or by placing a `-' at the front of the command. (Another quick note: the decision of whether to abort a target when one of its shell commands returns non-zero is left to the shell that is executing the commands. Some shells allow this ``error-checking'' to be switched on and off at will while others do not.)
PMake has the ability to save text in variables to be recalled later at your convenience. Variables in PMake are used much like variables in sh(1) and, by tradition, consist of all upper-case letters. They are assigned- and appended-to using lines of the form
VARIABLE = value VARIABLE += value
respectively, while being conditionally assigned-to (if not already defined) and assigned-to with expansion by lines of the form
VARIABLE ?= value VARIABLE := value
Finally,
VARIABLE != command
will execute command using the Bourne shell and place the result in the given variable. Newlines are converted to spaces before the assignment is made. This is not intended to be used with commands that produce a large amount of output. If you use it this way, it will probably deadlock.
Variables are expanded by enclosing the variable name in either parentheses or curly braces and preceding the whole thing with a dollar sign. E.g. to set the variable CFLAGS to the string ``-I/sprite/src/lib/libc -O'' you would place a line
CFLAGS = -I/sprite/src/lib/libc -O
in the makefile and use the word $(CFLAGS) wherever you would like the string ``-I/sprite/src/lib/libc -O'' to appear. To pass a string of the form ``$(name)'' or ``${name}'' through to the shell (e.g. to tell it to substitute one of its variables), you can use ``$$(name)'' and ``$${name}'', respectively, or, as long as the name is not a PMake variable, you can just place the string in directly, as PMake will not expand a variable it doesn't know, unless it is given one of the three compatibility flags -V, -B, or -M.
There are two distinct times at which variable substitution occurs: When parsing a dependency line, such substitution occurs immediately upon reading the line. Thus all variables used in dependency lines must be defined before they appear on any dependency line. For variables that appear in shell commands, variable substitution occurs when the command is processed, i.e. when it is prepared to be passed to the shell or before being squirreled away for later execution (qv. COMMANDS, above).
There are four different types of variables at which PMake will look when trying to expand any given variable. They are (in order of decreasing precedence): (1) variables that are defined specific to a certain target. These are the so-called ``local'' variables and will only be used when performing variable substitution on the target's shell script and in dynamic sources (see below for more details), (2) variables that were defined on the command line, (3) variables defined in the makefile and (4) those defined in PMake environment, as passed by your login shell. An important side effect of this searching order is that once you define a variable on the command line, nothing in the makefile can change it. Nothing.
As mentioned above, each target has associated with it as many as seven ``local'' variables. Four of these variables are always set for every target that must be re-created. Each local variable has a long, meaningful name and a short, one-character name that exists for backwards-compatibility. They are:
Three other ``local'' variables are set only for certain targets under special circumstances. These are the ``.IMPSRC'', ``.ARCHIVE'' and ``.MEMBER'' variables. When they are set, how they are used, and what their short forms are are detailed in later sections.
In addition, for you System V fans, the six variables ``@F'', ``@D'', ``<F'', ``<D'', ``*F'', and ``*D'' are defined to be the same as for the System V version of Make. If you don't know about these things, be glad.
Four of these local variables may be used in sources on dependency lines. The variables expand to the proper value for each target on the line. The variables are ``.TARGET'', ``.PREFIX'', ``.ARCHIVE'', and ``.MEMBER''.
In addition, certain variables are set by or have special meaning to PMake The .PMAKE (and MAKE) variable is set to the name by which PMake was invoked, to allow recursive makes to use the same version, whatever it may be. All command-line flags given to PMake are stored in the .MAKEFLAGS (and MFLAGS) variable just as they were given. This variable is also exported to subshells as the PMAKE environment variable.
Variable expansion may be modified as for the C shell. A general expansion specification looks like:
$(variable[:modifier[:...]])
Each modifier begins with a single character, thus:
In addition, PMake supports the System V form of substitution (string1=string2).
Makefile inclusion and conditional structures reminiscent of the C compiler have also been included in PMake
Comments begin with a `#' anywhere but in a shell command and continue to the end of the line. If the `#' comes at the beginning of the line, however, the following keywords are recognized and acted on:
This is very similar to the C compiler's file-inclusion facility, right down to the syntax. What follows the #include must be a filename enclosed either in double-quotes or angle brackets. Variables will be expanded between the double-quotes or angle-brackets. If angle-brackets are used, the system makefile directory is searched. If the name is enclosed in double-quotes, the including makefile's directory, followed by all directories given via -I arguments, followed by the system directory, is searched for a file of the given name.
If the file is found, PMake starts taking input from that file as if it were part of the original makefile.
When the end of the file is reached, PMake goes back to the previous file and continues from where it left off. This facility is recursive up to a depth limited only by the number of open files allowed to any process at one time.
These are all the beginnings of conditional constructs in the spirit of the C compiler. Conditionals may be nested to a depth of thirty.
In the expressions given above, op may be either || (logical OR) or && (logical AND). && has a higher precedence than ||. As in C, PMake will evaluate an expression only as far as necessary to determine its value. I.e. if the left side of an && is false, the expression is false and vice versa for ||. Parentheses may be used as usual to change the order of evaluation.
One other boolean operator is provided: ! (logical negation). It is of a higher precedence than either the AND or OR operators, and may be applied in any of the ``if'' constructs, negating the given function for ``#if'' or the implicit function for the other four.
Expr can be one of several things. Four functions are provided, each of which takes a different sort of argument.
The function defined is used to test for the existence of a variable. Its argument is, therefore, a variable name. Certain lower-case variable names (e.g. ``sun'', ``unix'' and ``sprite'') are defined in the system makefile (qv. FILES) to specify the sort of system on which PMake is being run. These are intended to make makefiles more portable. Any variable may be used as the argument of the defined function.
The make function is given the name of a target in the makefile and evaluates to true if the target was given on PMake command-line or as a source for the .MAIN target before the line containing the conditional.
The exists function takes a file name, which file is searched for on the system search path (as defined by .PATH targets (see below)). It evaluates true if the file is found.
empty takes a variable expansion specification (minus the dollar sign) as its argument. If the resulting expansion is empty, this evaluates true.
Expr can also be an arithmetic or string comparison, with the lefthand side being a variable expansion. The standard C relational operators are allowed, and the usual number/base conversion is performed, with the exception that octal numbers are not supported. If the righthand side of a "==" or "!=" operator begins with a quotation mark, a string comparison is done between the expanded variable and the text between the quotation marks. If no relational operator is given, it is assumed that the expanded variable is to be compared against 0, i.e. it is interpreted as a boolean, with a 0 value being false and a non-zero value being true.
When, in the course of evaluating one of these conditional expressions, PMake encounters some word it does not recognize, it applies one of either make or defined to it, depending on the form of ``if'' used. E.g. ``#ifdef'' will apply the defined function, while ``#ifnmake'' will apply the negation of the make function.
If the expression following one of these forms evaluates true, the reading of the makefile continues as before. If it evaluates false, the following lines are skipped. In both cases, this continues until either an #else or an #endif line is encountered.
The #else, as in the C compiler, causes the sense of the last conditional to be inverted and the reading of the makefile to be based on this new value. I.e. if the previous expression evaluated true, the parsing of the makefile is suspended until an #endif line is read. If the previous expression evaluated false, the parsing of the makefile is resumed.
The ``elif'' constructs are a combination of ``else'' and ``if,'' as the name implies. If the preceding ``if'' evaluated false, the expression following the ``elif'' is evaluated and the lines following it are read or ignored the same as for a regular ``if.'' If the preceding ``if'' evaluated true, however, the ``elif'' is ignored and all following lines until the ``endif'' (see below) are ignored.
#endif is used to end a conditional section. If lines were being skipped, the reading of the makefile resumes. Otherwise, it has no effect (the makefile continues to be parsed as it was just before the #endif was encountered).
Takes the next word on the line as a global variable to be undefined (only undefines global variables, not command-line variables). If the variable is already undefined, no message is generated.
In PMake files can have certain ``attributes.'' These attributes cause PMake to treat the targets in special ways. An attribute is a special word given as a source to a target on a dependency line. The words and their functions are given below:
As there were in Make, so there are certain targets that have special meaning to PMake. When you use one on a dependency line, it is the only target that may appear on the left-hand-side of the operator. The targets are as follows:
In addition to these targets, a line of the form
attribute : sources
applies the attribute to all the targets listed as sources except as noted above.
One of the best aspects of both Make and PMake comes from their understanding of how the suffix of a file pertains to its contents and their ability to do things with a file based solely on its suffix. PMake also has the ability to find a file based on its suffix, supporting different types of files being in different directories. The former ability derives from the existence of so-called transformation rules while the latter comes from the specification of search paths using the .PATH target.
A special type of dependency, called a transformation rule, consists of a target made of two known suffixes stuck together followed by a shell script to transform a file of one suffix into a file of the other. The first suffix is the suffix of the source file and the second is that of the target file. E.g. the target ``.c.o,'' followed by commands, would define a transformation from files with the ``.c'' suffix to those with the ``.o'' suffix. A transformation rule has no source files associated with it, though attributes may be given to one in the usual way. These attributes are then applied to any target that is on the ``target end'' of a transformation rule. The suffixes that are concatenated must be already known to PMake in order for their concatenation to be recognized as a transformation, i.e. the suffixes must have been the source for a .SUFFIXES target at some time before the transformation is defined. Many transformations are defined in the system makefile (qv. FILES) and I refer you there for more examples as well as to find what is already available (you should especially note the various variables used to contain flags for the compilers, assemblers, etc., used to transform the files. These variables allow you to customize the transformations to your own needs without having to redefine them). A transformation rule may be defined more than once, but only the last such definition is remembered by PMake This allows you to redefine the transformations in the system makefile if you wish.
Transformation rules are used only when a target has no commands associated with it, both to find any additional files on which it depends and to attempt to figure out just how to make the target should it end up being out-of-date. When a transformation is found for a target, another of the seven ``local'' variables mentioned earlier is defined:
For example, given the following makefile:
a.out : a.o b.o
$(CC) $(.ALLSRC)
and a directory containing the files a.o, a.c and b.c, PMake will look at the list of suffixes and transformations given in the built-in rules and find that the suffixes ``.c'' and ``.o'' are both known and there is a transformation rule defined from one to the other with the command ``$(CC) $(CFLAGS) -c $(.IMPSRC).'' Having found this, it can then check the modification times of both a.c and b.c and execute the command from the transformation rule as necessary in order to update the files a.o and b.o.
PMake unlike Make before it, has the ability to apply several transformations to a file even if the intermediate files do not exist. Given a directory containing a .o file and a .q file, and transformations from .q to .l, .l to .c and .c to .o, PMake will define a transformation from .q -> .o using the three transformation rules you defined. In the event of two paths between the same suffixes, the shortest path will be chosen between the target and the first existing file on the path. So if there were also a transformation from .l files to .o files, PMake would use the path .q -> .l -> .o instead of .q -> .l -> .c -> .o.
Once an existing file is found, PMake will continue to look at and record transformations until it comes to a file to which nothing it knows of can be transformed, at which point it will stop looking and use the path it has already found.
What happens if you have a .o file, a .q file and a .r file, all with the same prefix, and transformations from .q -> .o and .r -> .o? Which transformation will be used? PMake uses the order in which the suffixes were given on the .SUFFIXES line to decide between transformations: whichever suffix came first, wins. So if the three suffixes were declared
.SUFFIXES : .o .q .r
the .q -> .o transformation would be applied. Similarly, if they were declared as
.SUFFIXES : .o .r .q
the .r -> .o transformation would be used. You should keep this in mind when writing such rules. Note also that because the placing of a suffix on a .SUFFIXES line doesn't alter the precedence of previously-defined transformations, it is sometimes necessary to clear the whole lot of them out and start from scratch. This is what the .SUFFIXES-only line, mentioned earlier, will do.
PMake also supports the notion of multiple directories in a more flexible, easily-used manner than has been available in the past. You can define a list of directories in which to search for any and all files that aren't in the current directory by giving the directories as sources to the .PATH target. The search will only be conducted for those files used only as sources, on the assumption that files used as targets will be created in the current directory.
The line
.PATH : RCS
would tell PMake to look for any files it is seeking (including ones made up by means of transformation rules) in the RCS directory as well as the current one. Note, however, that this searching is only done if the file is used only as a source in the makefile. I.e. if the file cannot be created by commands in the makefile.
A search path specific to files with a given suffix can also be specified in much the same way.
.PATH.h : h /usr/include
causes the search for header files to be conducted in the h and /usr/include directory as well as the current one.
When expanding wildcards, these paths are also used. If the pattern has a recognizable suffix, the search path for that suffix is used. Otherwise, the path defined with the regular .PATH target is used.
When a file is found somewhere other than the current directory, its name is replaced by its full pathname in any ``local'' variables.
Two types of suffixes are given special attention when a search path is defined for them. On most systems, the C compiler lets you specify where to find header files (.h files) by means of -I flags similar to those used by PMake If a search path is given for any suffix used as a source for the .INCLUDES target, the variable $(.INCLUDES) will be set to contain all the directories on the path, in the order given, in a format which can be passed directly to the C compiler. Similarly, on some systems, one may give directories to search for libraries to the compiler by means of -L flags. Directories on the search path for a suffix which was the source of the .LIBS target will be placed in the $(.LIBS) variable ready to be passed to the compiler.
Two other special forms of sources are recognized by PMake Any source that begins with the characters ``-l'' or ends in a suffix that is a source for the .LIBS target is assumed to be a library, and any source that contains a left parenthesis in it is considered to be a member (or members) of an archive.
Libraries are treated specially mostly in how they appear in the local variables of those targets that depend on them. If the system supports the -L flag when linking, the name of the library (i.e. its ``-l'' form) is used in all local variables. PMake assumes that you will use the $(.LIBS) variable in the appropriate place. If, however, the system does not have this feature, the name is expanded to its full pathname before it is placed in any local variable.
One problem with libraries is they have a table of contents in them and when the file is touched (so the file's modification time and the time listed in the table of contents don't match), the library is declared to be ``out-of-date'' by the linker and the final linking stage of creating your program fails miserably. To avoid this problem, when you use the -t flag, PMake updates the time of the table of contents for the library, as well as the library itself.
The process of creating a library or archive can be a painful one, what with all the members having to be kept outside the archive as well as inside it in order to keep them from being recreated. PMake has been set up, however, to allow you to reference files that are in an archive in a relatively painless manner. The specification of an archive member is written as:
archive(member [member...])
Both the open and close parenthesis are required and there may be any number of members between them (except 0, that is). Members may also include wildcards characters. When such a source is examined, it is the modification time of the member, as recorded in the archive, that is used to determine its datedness.
If an archive member has no commands associated with it, PMake goes through a special process to find commands for it. First, implicit sources are sought using the ``member'' portion of the specification. So if you have something like ``libcompat.a(procFork.o)'' for a target, PMake attempts to find sources for the file ``procFork.o,'' even if it doesn't exist. If such sources exist, PMake then looks for a transformation rule from the member's suffix to the archive's (in this case from .o -> .a) and tacks those commands on as well.
To make these transformations easier to write, three local variables are defined for the target:
Using the transformations already in the system makefile, a makefile for a library might look something like this:
OBJS = procFork.o procExec.o procEnviron.o fsRead.o
.o.a :
...
rm -f $(.MEMBER)
lib.a : lib.a($(OBJS))
ar cru $(.TARGET) $(.OODATE)
ranlib $(.TARGET)
You might be wondering, at this point, why I did not define the .o -> .a transformation like this:
.o.a :
ar r $(.ARCHIVE) $(.TARGET)
...
rm -f $(.TARGET)
The reason is simple: you cannot execute ``ar'' on the same file several times at once. If you try, you end up with a corrupted archive. So rather than reduce PMake to executing only one job at a time, I chose to archive all the out-of-date files at once (this turns out to be faster anyway).
When creating targets in parallel, several shells are executing at once, each wanting to write its own two cent's worth onto the screen. This output must be captured by PMake in some way in order to prevent the screen from being filled with garbage even more indecipherable than one can already get from these programs. PMake has two ways of doing this, one of which provides for much cleaner output and a clear delineation between the output of different jobs, the other of which provides a more immediate response so one can tell what is really happening. The former is done by notifying the user when the creation of a given target starts, capturing the output, and transferring it to the screen when the job finishes, preceded by an indication as to which job produced the output. The latter is done by catching the output of the shell (and its children) and buffering it until an entire line is received, then printing that line preceded by the name of the job from which the line came. The name of the job is just the target which is being created by it. Since I prefer this second method, it is the one used by default. The first method will be used if the -P flag is given to PMake
As mentioned before, PMake attempts to create several targets at once. On some systems where load balancing or process migration is in effect, the amount of concurrency which can be used will be much greater than on others. During the development of PMake I found that while one could create up to five targets at once on a Sun 3 without making the machine unusable, attempting the same feat on a Sun 2 would grind the machine into the dirt, most likely making the whole process run slower than it would have under Make. In addition, the use of PMake on a multi-user machine (in contrast to a workstation) calls for judicious use of concurrency to avoid annoying the other users. The ability to execute tasks in parallel, in combination with the execution of only one shell per target, brings about decreases in creation time on the order of 25%-60%.
The -J and -L flags are used to control the number of shells executing at once and should be used to find the best level for your machine. Once this is found, the default level can be set at that point and PMake recompiled.
PMake was designed to be as backwards-compatible with Make as possible. In spite of this, however, there are a few major differences which may cause problems when using old makefiles:
prod : $(PROGRAM) clean
This is liable to cause some of the object files to be removed after having been created during the current invocation (or, at the very least, the object files will not be removed when the program has been made), leading to errors in the final linking stage. This problem cannot even be gotten around by limiting the maximum concurrency to one, since the traversal of the dependency graph is done in a breadth-first, rather than a depth-first way. This can only be gotten around by rewriting the makefile, or by invoking PMake with the -M flag.
One other possible conflict arises because PMake forks only one shell to execute the commands to re-create a target. This means that changes of directory, environment, etc., remain in effect throughout the creation process. It also allows for a more natural entry of shell constructs, such as the ``for'' and ``while'' loops in the Bourne shell, without the need for backslashes and semi-colons required by the one-shell-per-command paradigm used by Make. This shouldn't pose any serious difficulties (or even any trivial ones so far as I can see), but should, in fact, make life a little easier. It is, however, possible to have PMake execute each command in a single shell by giving it the -B flag.